<%
$:.unshift File.expand_path(File.dirname(__FILE__), "/../lib/table_fu")
require 'rubygems'
require 'table_fu'

require 'uv'

def code_for(file, output=true)
  return '' unless File.exists?("examples/#{file}.rb")
  file = File.open("examples/#{file}.rb").read
  html = Uv.parse(file, "xhtml", "ruby", false, "dawn", false)
  out = ''
  if output
    csv =<<-CSV
Author,Best Book,Number of Pages,Style
Samuel Beckett,Malone Muert,120,Modernism
James Joyce,Ulysses,644,Modernism
Nicholson Baker,Mezannine,150,Minimalism
Vladimir Sorokin,The Queue,263,Satire
    CSV
    if block_given?
      out = yield instance_eval(file)
    else
      out = instance_eval(file).inspect
    end
    out = "<em>Returns:</em>" + Uv.parse(out, 'xhtml', 'ruby', false, 'dawn', false)
  end
  "#{html}#{out}"
end %>
<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
    <title>TableFu</title>
    <link rel="stylesheet" type="text/css" href="documentation/css/styles.css" />
    <link rel="stylesheet" type="text/css" href="documentation/css/dawn.css" />
  </head>

  <body>
    <a href="http://www.propublica.org" class="propublica">&nbsp;</a>
    <h1>TableFu <small>&ndash; Version: <%=
    config = YAML.load(File.read('VERSION.yml'))
    "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
    %></small></h1>

    <p><a href="http://github.com/propublica/table-fu">TableFu</a> is a ruby gem for spreadsheet-style handling of arrays (e.g. filtering, formatting, and sorting by "column" or "row"). In addition, it has the ability to <a href="#facet">facet</a> &mdash; or group &mdash; rows according to cell value. It was developed as a backend for its companion project <a href="http://www.github.com/propublica/table-setter">TableSetter</a>.</p>
    <p>For example, <strong>TableFu</strong> can consume a csv file and sort on a column:
        <%= code_for "sort_by_column" do |ret|
              ret.rows.inspect
            end
        %>
    </p>
    <h2><a id="toc">Table of Contents</a></h2>
    <ul>
      <li><a href="#installation">Installation</a></li>
      <li><a href="#usage">Usage</a></li>
      <li><a href="#macros">Macros / Formatting</a></li>
      <li><a href="#faceting">Faceting</a></li>
      <li><a href="#manipulation">Manipulation</a></li>
      <li><a href="#links">Links</a></li>
      <li><a href="#credits">Credits</a></li>
      <li><a href="#license">License</a></li>
    </ul>
    <h2><a id="installation" href="#toc">Installation</a></h2>
    <p><strong>TableFu</strong> is available as a rubygem:
<pre class="dawn">
 gem install table_fu</pre>
      or from the actual source:
<pre class="dawn">
 git clone git://github.com/propublica/table-fu.git
 cd table-fu
 rake install</pre>
</p>
    <h2><a id="usage" href="#toc">Usage</a></h2>
    <p>
      The <strong>TableFu</strong> constructor takes two arguments; a 2 dimensional array or csv (file object or string) and a hash of column options or a block. TableFu will assume that the first row of the array contains the column headers. The simple options are:</p>
      <p><strong>sorted_by:</strong> the column to sort by, it defaults to no sorting at all.
      <%= code_for "sort_by_column" do |ret|
            ret.rows.inspect
          end
      %>
    </p>
    <p><strong>columns:</strong> the columns to include in the table, useful when reordering and filtering extraneous columns.  If no arguments are provided, <strong>TableFu</strong> will include all columns by default.
    <%= code_for "columns" %>
    Note that the columns are still accessible directly even if they're not in the columns array.
    <%= code_for "columns_hidden" %>
    </p>

    <h2><a id="macros" href="#toc">Macros / Formatting</a></h2>
    <p><strong>TableFu</strong> allows you to format columns of cells through the use of macros. See <a href="http://github.com/propublica/table-fu/blob/master/lib/table_fu/formatting.rb"><strong>TableFu::Formatting</strong></a> for the predefined macros available. </p>
    <p>The <strong>formatting</strong> attribute should be a hash of the form:
        <%= code_for "formatting_options", false %>
        which will call the macro on the column name with the arguments if specified.
    </p>
    <p>For example, you can use the <strong>last_name</strong> formatter to extract the last name of a cell containing a person's name:
      <%= code_for "last_name" %>
    </p>

    <p>Of course, you can provide your own macros by patching <a href="http://github.com/propublica/table-fu/blob/master/lib/table_fu/formatting.rb">TableFu::Formatting</a>. <a href="http://www.github.com/propublica/table-setter">TableSetter</a> includes rails view helpers directly in <strong>TableFu::Formatting</strong>.
      <%= code_for "rails_helpers", false %>
    </p>

    <h2><a id="faceting" href="#toc">Faceting</a></h2>
    <p>Faceting provides a way to group rows together using a cell value they share in common. Calling <strong>TableFu#faceted_by</strong> returns an array of table fu instances each with a <strong>faceted_on</strong> attribute and with only the rows where that value appears.
    </p>
    <p>In this example there are 2 rows where "Modernism" appears in the style column, so calling <strong>faceted_on</strong> with the argument <strong>"Style"</strong> returns a <strong>TableFu</strong> instance with those rows grouped together:
    <%= code_for "faceting" do |s|
      s.map { |table|
        "table.faceted_on => #{table.faceted_on}, table.rows => #{table.rows.inspect}\n"
      }.join('')
    end %>
    </p>
    <h2><a id="manipulation" href="#toc">Manipulation / Output</a></h2>
    <h3>Deleting Rows</h3>
    <p>In addition to hiding columns and faceting <strong>TableFu</strong> can delete rows from the csv. Let's get rid of James Joyce (no one ever finished <em>Ulysses</em> anyway):
      <%= code_for "zap_joyce" do |s|
        s.rows.inspect
      end %>
      The deleted rows are still available in <strong>@deleted_rows</strong> for later access:
      <%= code_for "zap_joyce" do |s|
        "table.deleted_rows => #{s.deleted_rows.inspect}"
      end %>
    </p>
    <h3>Pagination</h3>
    <p>If you want only a chunk of the data, say to paginate your table, you can call <strong>only!</strong> with the range of values you want to keep:
      <%= code_for "only" %>
    </p>
    <h3>Sum</h3>
    <p>TableFu can also sum a column of values:
      <%= code_for "totals" %>
    </p>
    <h2><a id="links" href="#toc">Links</a></h2>
    <ul>
      <li><a href="http://github.com/propublica/table-setter">TableSetter</a><br>A Sinatra app that uses <strong>TableFu</strong> to render public Google Spreadsheets in custom HTML.</li>
      <li><a href="http://github.com/propublica/table-setter-generator">TableSetter Generator</a><br>
        A rails generator that allows you to create a rails app like TableSetter.
      </li>
      <li><a href="http://github.com/propublica/table-fu/issues">Issues</a><br>Post bug reports and feature requests here.</li>
      <li><a href="doc/index.html">API Docs</a></li>
    </ul>
    <h2><a id="credits" href="#toc">Credits</a></h2>
    <p><a href="http://github.com/thejefflarson">Jeff Larson</a> (Maintainer),
      <a href="http://github.com/brianboyer/">Brian Boyer</a>,
      <a href="http://github.com/kleinmatic">Scott Klein</a>,
      <a href="http://github.com/markpercival">Mark Percival</a>,
      <a href="http://github.com/seebq">Charles Brian Quinn</a>, and
      <a href="http://github.com/jpmckinney">James McKinney</a>.</p>.</p>
    <h2><a id="license" href="#toc">License</a></h2>
    <pre><%= File.open("LICENSE").read %></pre>
  </body>
</html>
